<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Strict//EN">
<html>

<head>
<meta http-equiv="Content-Language" content="en-us">
<title>User parameters</title>
<link rel="stylesheet" type="text/css" href="../style.css">
</head>

<body>

<div align="center">
<table class=allEncompassingTable >
 <tr>
  <td >
<p><a href="../index.html" TARGET="_top"><img src="images/homeImg.png"></a></p>



<h1>User parameters</h1>


<p>Each object that is also associated with a script can have user parameters attached. Those parameters can be used as a quick way of adjusting values of a specific <a href="models.htm">model</a> for example (e.g. the maximum velocity of a mobile robot or the resolution of a sensor). When enabled, a user parameter icon will display next to the script icon in the <a href="userInterface.htm#SceneHierarchy">scene hierarchy</a>:</p>

<p align=center><img src="images/scriptSimParams1.jpg"></p>
<p class=imageLabel>[User parameter icon]</p>
<br>

<p>Double-clicking the icon opens the user parameter dialog:</p>

<p align=center><img src="images/scriptSimParams2.jpg"></p>
<p class=imageLabel>[User parameter dialog]</p>
<br>

<p>If the user modifies a value in the parameter list, scripts can react to that modification and adjust their behavior accordingly. A script can use the <a href="regularApi/simGetUserParameter.htm">sim.getUserParameter</a> function to retrieve the value of a parameter, or the <a href="regularApi/simSetUserParameter.htm">sim.setUserParameter</a> function to modify the value of a parameter. When the user parameter list for an object is empty, the user parameter icon won't show. To enable it for a specific object, just type <em>sim.setUserParameter(objectHandle,'@enable','')</em>, and make sure the object is associated with a script.</p>

<p>Following are the items in the user parameter dialog: <br>
</p>

<li><strong>Add new parameter</strong>: adds a new parameter to the list.<br>
</li>

<li><strong>User parameters</strong>: list of parameters. Individual parameters can be renamed with a double-click, and their values modified.<br>
</li>

<li><strong>Value</strong>: string value of the parameter. The string can contain any value, including embedded zeros.<br>
</li>

<li><strong>Unit</strong>: the unit of the value (if applicable). The unit is merely intended to inform the user.<br>
</li>

<li><strong>Parameter is private</strong>: if enabled, then the selected parameter is not shown during a simulation (in that case the parameter is probably not meant to be modified during a simulation).<br>
</li>

<li><strong>Parameter is persistent</strong>: if enabled, then the selected parameter will not be restored to its original value at simulation end.<br>
</li>

<p>User parameters represent a simple way to adjust specific values via a dialog. A more flexible behaviour can be achieved by using <a href="userConfigCallbackFunctions.htm">user config callback functions</a>: if such a callback function is defined in a customization script attached to an object, then double-clicking the user parameter icon will instead call that callback function, where the user can prepare a more elaborate user interaction dialog for instance.</p>


<br>
<h3 class=recommendedTopics>Recommended topics</h3>

<li><a href="apiFunctionListCategory.htm#userParameters">Related API functions</a></li>
<li><a href="userConfigCallbackFunctions.htm">User config callback functions</a></li>
<br>
<br>
 </tr>
</table> 
</div>  
  
  
</body>

</html>
